using System;
using System.Collections.Generic;
using System.Text;
using SharpMud.MudLib.Common.Entities;

namespace SharpMud.MudLib.Common.Environment
{
    /// <summary>
    /// Used to outline the describability of items, exits, mobiles, and characters.
    /// </summary>
    /// <remarks>
    /// During a look [around] command, the return values of GetDeclarativeShortDescription() 
    /// &amp; GetIntegralShortDescription() are used. If they return null, or are trimmed to a
    /// length of 0, then their values are ignored. (This is used to indicate that an item is
    /// invisible to the looker, or has no applicable description for the context.)
    /// 
    /// During a look [at] command, GetLongDescription() is used. A null return value or a value
    /// trimmed to zero length may indicate that the looker is unable to retrieve a description,
    /// but it is up to the look command to handle that.
    /// </remarks>
    public interface IDescribable
    {
        /// <summary>
        /// Used to get the short description of something,
        ///  in the shortest form that can descriptively refer to this IDescribable.
        /// Used as a list item for room and inventory contents.
        /// </summary>
        /// <remarks>
        /// May also be used internally (by the interface implementer) to construct the GetDeclarativeShortDescription()
        /// </remarks>
        /// <example>
        /// Examples, depending on implementer:
        ///		Item	-	"a shiny broadsword"
        ///		Exit	-	"a small wooden door"
        ///		Mobile	-	"a friendly stray dog"
        ///		Player	-	"Bruce"
        ///		Player	-	"Illuminus, the Artificer"
        /// </example>
        string GetShortDescription(ICharacter looker);

        /// <summary>
        /// Used to get the short description of something,
        ///  in the form that declares this IDescribable's presence in a room
        /// Used to list this IDescrbable explicitly as something that is in the room,
        /// for a look command.
        /// </summary>
        /// <example>
        /// Examples, depending on implementer:
        ///		Item	-	"A shiny broadsword is laying here"
        ///		Exit	-	N/A	- returns String.Empty
        ///		Mobile	-	"A friendly stray dog is here, nipping at trash"
        ///		Player	-	"Bruce is laying down here, recuperating from battle"
        ///		Player	-	"Illuminus, the Artificer is standing here"
        /// </example>
        string GetDeclarativeShortDescription(ICharacter looker);

        /// <summary>
        /// Used to get the short description of something,
        ///  in the form that declares this IDescribable's presence in a room,
        ///  using a full (but single) sentence with narrative style.
        /// </summary>
        /// <remarks>
        /// Appended to the parent room's long description during a look command.
        /// If the return value is trimmed to a length of zero, (or is null), it will be ignored
        /// when the parent room's long description is generated.
        /// </remarks>
        /// <example>
        /// Examples, depending on implementer:
        ///		Item	-	"A shiny broadsword is laying here, obscured by the dust."
        ///		Exit	-	"A small wooden door is barely visible to the east."
        ///		Mobile	-	"A friendly stray dog is here, sniffing about."
        ///		Player	-	N/A - returns String.Empty
        ///		Player	-	"The room glows with the presence of an Immortal."
        /// </example>
        string GetIntegralShortDescription(ICharacter looker);

        /// <summary>
        /// Used to get the long description of something,
        ///  in the form that declares this IDescribable's presence in the room,
        ///  using a full (but single) sentence with narrative style.
        /// </summary>
        string GetLongDescription(ICharacter looker);
    }
}
